Reasons for ASPNETCORE_ENVIRONMENT Failure

TLDR

• After setting ASPNETCORE_ENVIRONMENT in Windows global environment variables, an ASP.NET Core application may not immediately read the new setting.
• Simply restarting the website or the Application Pool does not update the environment variables read by IIS.
• You must execute the iisreset command to force a restart of the IIS service to ensure the environment variable changes take effect.

Scenarios Where Environment Variable Settings Fail

This issue occurs when you modify the ASPNETCORE_ENVIRONMENT environment variable via global system settings in a Windows Server environment, but the application continues to read the default appsettings.json instead of switching to the corresponding appsettings.{Environment}.json.

In ASP.NET Core applications hosted on IIS, even if environment variables are correctly set at the operating system level, the IIS process (w3wp.exe) often fails to detect changes to system environment variables in real-time due to caching mechanisms or service lifecycle management. In this case, simply "stopping and starting the website" or "recycling the Application Pool" is insufficient to force IIS to re-read global system environment variables.

Solution and Verification

When to perform this action: When you have confirmed that the environment variables have been correctly written to the system settings, but the application behavior has not changed as expected.

To make the changes take effect, you must force a restart of the IIS service. Open Command Prompt (CMD) or PowerShell as an administrator and execute the following command:

iisreset /restart

TIP

Executing the iisreset command will interrupt all hosted website services on the server. Please ensure you perform this during maintenance windows or after confirming the impact on business operations.

After execution, IIS will reload all environment variables, and the application will be able to correctly read the configured ASPNETCORE_ENVIRONMENT value.

Change Log

• 2024-09-19 Initial document creation.